GetScrap

GetScrap
Header:	Scrap.h		Carbon status:	Unsupported

Reads data from the scrap.

SInt32 GetScrap (
    Handle hDest, 
    ResType theType, 
    SInt32 *offset
);

hDest: A handle to the memory location where the function should place the data from the scrap. The function makes a copy of the data in memory and sets the handle specified by the hDest parameter to refer to this copy, resizing the handle if necessary. If you specify NULL in this parameter, the function does not read in the data but does return the offset of the data in the scrap and the number of bytes of the requested scrap data type if the requested type exists in the scrap.
theType: The scrap format type of the data you wish to read from the scrap.
offset: On return, a pointer to the location of the data in the scrap. This value is expressed as an offset (in bytes) from the beginning of the scrap. The returned value for the offset parameter is valid only if the Translation Manager isn’t available; if the Translation Manager is available, then the value of offset is undefined.

function result: The length (in bytes) of the data or a negative function result that indicates the error. If the function returns noTypeErr, then the data in the scrap isn’t available in the scrap format type requested by your application. If the Translation Manager is available and the function returns the constant noTypeErr, this value also indicates that the Translation Manager could not find any translators to convert the data into the scrap format type requested by your application0

DISCUSSION

Your application can use this function multiple times to read different formats of the same data from the scrap. If more than one format of the same scrap format type exists in the scrap, the function returns the first occurrence of that format type that it finds. For example, if data of type 'TEXT', 'PICT', and 'TEXT' exist on the scrap, and your application requests the data in the scrap with scrap format type 'TEXT', the function returns the first data of type 'TEXT' that it finds.

If your application supports more than one scrap format type, your application should attempt to read its preferred scrap format type first. If your application doesn’t prefer one scrap format type over any other type, it should try reading each of the scrap format types that it supports and use the type that returns the lowest offset. The scrap format type with the lowest offset indicates that this format type was written before any of the others and therefore was preferred by the application that wrote it.

If you request a scrap format type that isn’t in the scrap and the Translation Manager is available, the Scrap Manager uses the Translation Manager to convert the data of a scrap format type that does exist in the scrap into the scrap format type requested by your application. For example, if the SurfWriter application requests data from the scrap in the 'SURF' scrap format type, and the data in the scrap is available in the format types 'TEXT', 'PICT', and 'SDBS'(SurfDB’s private scrap format type), the Scrap Manager uses the Translation Manager to convert any one of the scrap format types 'TEXT', 'PICT', or 'SDBS' into the 'SURF' scrap format type. The Translation Manager looks for a translator that can perform one of these translations. If such a translator is available (for example, a translator that can translate the 'SDBS' scrap format type into the 'SURF' scrap format type), the Translation Manager uses the translator to translate the data in the scrap into the requested scrap format type. If the translation is successful, the Scrap Manager returns to your application the data from the scrap in the requested scrap format type.

The scrap format type is a four-character sequence that defines the type of data.

typedef FourCharCode ResType;

The standard scrap format types are

'TEXT': a series of ASCII characters
'PICT': a QuickDraw picture, which is a saved sequence of QuickDraw commands that can be displayed using the DrawPicture function

Optional scrap format types include

'styl': a series of bytes that have the same format as a TextEdit 'styl' resource and that describe styled text data
'snd ': a series of bytes that have the same format as an 'snd ' resource and that define a sound
'movv': a series of bytes that have the same format as an 'movv' resource and that define a movie

Your application should support the 'TEXT' and 'PICT' scrap format types and should optionally support any other scrap format types (such as 'snd ') that are appropriate to your application.

In general, when your application writes data to the scrap, the Scrap Manager appends the data to the scrap in the following format: the first 4 bytes are the scrap type format; the next 4 bytes are the length of the following data in bytes; and the remaining n bytes (where n is an even number) are the data.

If your application uses TextEdit to handle text in its documents, use TextEdit functions to implement the paste operation and to copy data from the scrap to the TextEdit scrap. If your application uses the Dialog Manager to handle editable text items in your application’s dialog boxes and a dialog box is the frontmost window, use the Dialog Manager function DialogPaste to copy data from the scrap to the current editable text item.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

AVAILABILITY

Not supported in Carbon. Not available in CarbonLib, but available when InterfaceLib 7.1 or later is installed. Exported by InterfaceLib 7.1 and later.

CARBON NOTES

You should instead use the functions ScrapHasFlavor, GetScrapFlavorSize, and GetScrapFlavorData.